feat: add the GraphQL WebSocket client (G4, graphql-transport-ws) - #1594

Closes #1586. Part of #1581.

Draft: depends on #1566 and #1568 (#1567, snag S1). This branch is the G4 server branch (#1593) merged with fix/websocket-client-shared-event-loop, so the diff against #1593 also shows the commits of #1566 and #1568 until they are merged. Once they are, I'll rebase and mark this ready.

Summary

GraphqlClientAdapter graphql = new GraphqlClientAdapter(getContext());
graphql.setClient(restletClient);                         // started Netty HTTP client with a context
graphql.setEndpoint("https://api.example.com/graphql");   // wss://api.example.com/graphql
graphql.setSubscriptionTransport(GraphqlTransport.WEBSOCKET);
graphql.setConnectionInitPayload(Map.of("token", token));
graphql.start();
Publisher<ExecutionResult> events = graphql.subscribe("subscription { issueUpdated { id } }", null, null);

• subscribe() multiplexes operations over one graphql-transport-ws connection, opened on the first demand (with connection_init and a 10 s acknowledgement timeout) and reopened if it was closed.
• Shared engine: the WebSocketClient borrows the event loop of the adapter's HTTP client through WebSocketClient.setClient (fix: let WebSocketClient share a borrowed client's event loop #1568), so the extension creates no Netty event loop group. stop() stops the WebSocket client but never the borrowed HTTP client.
• Each operation is delivered by its own virtual thread, honoring demand. graphql-transport-ws has no flow control: results received without demand are buffered up to maxResponseBytes per operation; beyond it the operation fails with a GraphqlTransportException and the server is sent complete, which cancels the server-side subscription.
• Errors before execution (error message) are a single result with errors, as with HTTP and SSE. A closed connection fails its operations with the close code and reason. cancel() sends complete.
• The request customizer adds handshake headers (for example an API key); the connection_init payload carries tokens for servers that authenticate there.
• The WebSocket code is only loaded when the transport is selected; org.restlet.ext.websocket stays optional.

Finding on #1568

WebSocketClient.setClient requires the borrowed client to have a Context (it reads the helper from the context attributes). new Client(Protocol.HTTP) has none, so it can't be borrowed: new Client(new Context(), Protocol.HTTP) is needed. Worth a clearer error message or a fallback there.

Validation

./mvnw -B verify -P default,test -pl org.restlet.ext.graphql (with core and the WebSocket extension from this branch): 63 tests, 0 failures; 91.6% instruction coverage (gate 80%); Spotless, SpotBugs, Javadoc, -Werror and dependency convergence pass.

New GraphqlWebSocketClientTestCase (7 tests) against GraphqlServerAdapter: a subscription and a query share one upgrade (counted by a filter) with demand honored, the init payload and a handshake header reaching data fetchers; cancelling one of two subscriptions cancels it on the server; adapter stop fails the other one and keeps the borrowed client; errors before execution as results; buffered results bounded, cancelling the server-side subscription; server shutdown (1001) fails subscriptions; endpoint without WebSocket; a borrowed client that isn't a started Netty client is rejected at start().

🤖 Generated with Claude Code